//--------------------------------------------------------------------------
// 
//  Copyright (c) Chili Software.  All rights reserved. 
// 
//  File: IPersistentTypeSelector.cs
//
//  Description: This interface allows a persistent to specify the 
//               persistent class that should be created from a data record.
// 
//--------------------------------------------------------------------------

using System;
using System.Collections.Generic;
using System.Text;
using System.Data;

namespace Chili.Opf3
{
	/// <summary>
	/// This interface is implemented if a persistent wants to create persistent types
	/// depending on the content of the current data record.
	/// </summary>
	/// <remarks>
	/// <para>
	/// Classes that create persistent types depending on the content of the current
	/// data record should implement this interface. It allows to return a type that 
	/// is created instead of the class that is implementing this interface. Usually
	/// that is a class that inherits of the persistent that implements this interface.
	/// </para>
	/// <para>
	/// If null is returned the current record is ignored (no persistent object instance
	/// is created from the current record).
	/// </para>
	/// </remarks>
	/// <example>
	/// The following sample shows the usage of this interface.
	/// <code lang="CS">
	/// [Persistent("USERS")]
	/// public class User : IPersistentTypeSelector
	/// {
	///		// ... Properties and fields of the persistent.
	/// 
	///		private Type FetchPersistentType(IDataRecord dataRecord)
	///		{
	///			if (e.DataRecord["Type"] == "1")
	///			{
	///				// Switch the type of the persistent that is created to User1.
	///				return typeof(User1);
	///			}
	///			else if ((bool)e.DataRecord["Ignore"])
	///			{
	///				// Tell the framework to ignore this item.
	///				return null;
	///			}
	///			// Have a persistent of type User created.
	///			return typeof(User);
	///		}
	/// }
	/// 
	/// // This class inherits from User.
	/// public class User1 : User
	/// {
	///		// ... Properties and fields of the object.
	/// }
	/// </code>
	/// </example>
	public interface IPersistentTypeSelector
	{
		/// <summary>
		/// Returns the type of the persistent object to create.
		/// </summary>
		/// <param name="dataRecord">The current record returned by the storage.</param>
		/// <returns>A type or null if the current record should be ignored.</returns>
		Type FetchPersistentType(IDataRecord dataRecord);
	}
}
